home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / os2tools / aping / cpicerr.h < prev    next >
Encoding:
Text File  |  1992-06-15  |  18.4 KB  |  446 lines
  1. /*****************************************************************************
  2.  *
  3.  *  MODULE NAME: CPICERR.H
  4.  *
  5.  *  COPYRIGHTS:
  6.  *             This module contains code made available by IBM
  7.  *             Corporation on an AS IS basis.  Any one receiving the
  8.  *             module is considered to be licensed under IBM copyrights
  9.  *             to use the IBM-provided source code in any way he or she
  10.  *             deems fit, including copying it, compiling it, modifying
  11.  *             it, and redistributing it, with or without
  12.  *             modifications.  No license under any IBM patents or
  13.  *             patent applications is to be implied from this copyright
  14.  *             license.
  15.  *
  16.  *             A user of the module should understand that IBM cannot
  17.  *             provide technical support for the module and will not be
  18.  *             responsible for any consequences of use of the program.
  19.  *
  20.  *             Any notices, including this one, are not to be removed
  21.  *             from the module without the prior written consent of
  22.  *             IBM.
  23.  *
  24.  *  AUTHOR:    Peter J. Schwaller
  25.  *             VNET:     PJS at RALVM6           Tie Line: 444-4376
  26.  *             Internet: pjs@ralvm6.vnet.ibm.com     (919) 254-4376
  27.  *             John Q. Walker
  28.  *             VNET:     JOHNQ at RALVM6         Tie Line: 444-4414
  29.  *             Internet: johnq@ralvm6.vnet.ibm.com   (919) 254-4414
  30.  *
  31.  *  AVAILABILITY:
  32.  *             These sample programs and source are also available on
  33.  *             CompuServe through the APPC Information Exchange.  To get
  34.  *             to the APPC forum just type 'GO APPC' from any CompuServe
  35.  *             prompt.  The samples are available in the Sample Programs
  36.  *             library section.  Just search on the keyword CPICPGMS to
  37.  *             find all the samples in this series.
  38.  *
  39.  *             Updates for the sample programs and support for many more
  40.  *             CPI-C platforms will also be made available on CompuServe.
  41.  *
  42.  *  RELATED FILES:
  43.  *             Use CPICERR.C
  44.  *
  45.  *****************************************************************************/
  46.  
  47. /*****************************************************************************
  48.  *
  49.  * OVERVIEW OF CPICERR CALLS
  50.  *
  51.  * cpicerr_new()                      Creates a CPICERR object.
  52.  *                                    This must be done before any other
  53.  *                                    cpicerr calls can be used.
  54.  *
  55.  * These calls set values in the cpicerr object structure and affect how
  56.  * cpicerr_handle_rc reacts to errors.
  57.  *
  58.  * cpicerr_set_log_file_name()        What filename to use for logging
  59.  * cpicerr_set_log_file_path()        Where the filename is
  60.  * cpicerr_set_program_name()         String - Output as part of log info
  61.  * cpicerr_set_program_info()         String - Output as part of log info
  62.  * cpicerr_set_major_version()        8 bit int - see cpicerr_exchange_version
  63.  * cpicerr_set_minor_version()        8 bit int - see cpicerr_exchange_version
  64.  * cpicerr_set_conv_id()              Used to extract conversation state info
  65.  * cpicerr_set_exit_level()           Level of error on which to exit
  66.  * cpicerr_set_show_level()           Level of error on which to show errors
  67.  * cpicerr_set_log_level()            Level of error on which to log errors
  68.  *
  69.  * cpicerr_handle_rc()                Should be called by the program for all
  70.  *                                    UNEXPECTED return codes.
  71.  *                                    Functions performed are:
  72.  *                                       Classification of the return code
  73.  *                                       Showing partial info to end user
  74.  *                                       Logging complete info to disk
  75.  *
  76.  * cpicerr_destroy()                  Destroys the CPICERR  object.
  77.  *
  78.  *
  79.  * cpicerr_classify_rc()              These are internal calls used by
  80.  * cpicerr_show_rc()                  other cpicerr_handle_rc.
  81.  * cpicerr_log_cpicerr()
  82.  * cpicerr_get_message()
  83.  * cpicerr_free_cpicerr()
  84.  * cpicerr_set_rc_info()
  85.  * cpicerr_show_product_info()
  86.  *
  87.  *****************************************************************************/
  88.  
  89. #ifndef INCL_CPICERR
  90. #define INCL_CPICERR
  91.  
  92. /*
  93.  * Collection of routines with special ported version for each platform
  94.  * The only thing that is used from CPICPORT.H is the correct setting
  95.  * of the SHORT_IDENTIFIERS and TIME_NOT_SUPPORTED identifiers.
  96.  */
  97. #include "cpicport.h"
  98.  
  99. #if defined(SHORT_IDENTIFIERS)
  100. /*
  101.  * The C/370 compiler requires that identifier be unique in the 1st 8 chars.
  102.  * If any new functions are added to this file, they should also be added to
  103.  * this list, with a unique mapping.
  104.  */
  105.     #define  cpicerr_classify_rc          cecr
  106.     #define  cpicerr_destroy              cedestroy
  107.     #define  cpicerr_free_cpicerr         ceff
  108.     #define  cpicerr_get_message          cegm
  109.     #define  cpicerr_handle_rc            cehr
  110.     #define  cpicerr_new                  cenew
  111.     #define  cpicerr_log_cpicerr          celf
  112.     #define  cpicerr_set_conv_id          cesci
  113.     #define  cpicerr_set_exit_level       cesxl
  114.     #define  cpicerr_set_log_file_name    ceslfn
  115.     #define  cpicerr_set_log_file_path    ceslfp
  116.     #define  cpicerr_set_log_level        cesll
  117.     #define  cpicerr_set_program_info     cespi
  118.     #define  cpicerr_set_program_name     cespn
  119.     #define  cpicerr_set_minor_version    ceminor
  120.     #define  cpicerr_set_major_version    cemajor
  121.     #define  cpicerr_set_rc_info          cesetr
  122.     #define  cpicerr_set_show_level       cessl
  123.     #define  cpicerr_show_product_info    cespri
  124.     #define  cpicerr_show_rc              cesr
  125.     #define  cpicerr_verbs_short          cvshort
  126.     #define  cpicerr_verbs_long           cvlong
  127.     #define  cpicerr_return_codes         cerc
  128.     #define  cpicerr_rc_classes           cercclass
  129.     #define  cpicerr_states_conv          cestate
  130.     #define  cpicerr_conv_types           ceconv_type
  131.     #define  cpicerr_sync_levels          cesync
  132.     #define  cpicerr_exchange_version     ceev
  133. #endif
  134.  
  135. #ifndef TIME_NOT_SUPPORTED
  136. /* Needed for the time_t structure used within the CPICINIT structure */
  137. #include <time.h>
  138. #endif
  139.  
  140. /*
  141.  * Specify the maximum sizes for a variety of CPI-C fields.
  142.  * The +1 is added to allow room for the C null terminator for strings.
  143.  */
  144. #define  MAX_LU_ALIAS      (8+1)
  145. #define  MAX_PLU_ALIAS     (8+1)
  146. #define  MAX_TP_NAME       (64+1)
  147. #define  MAX_SYM_DEST_NAME (8+1)
  148. #define  MAX_FQPLU_NAME    (17+1)
  149. #define  MAX_DESTINATION   (17+1)
  150. #define  MAX_MODE_NAME     (8+1)
  151. #define  MAX_USERID        (8+1)
  152. #define  MAX_PASSWD        (8+1)
  153.  
  154. /*****************************************************************************
  155.  * These values are used to break the CPI-C return codes down into classes.
  156.  * They are organized from errors that can be ignored, to fatal errors
  157.  * which cannot be recovered from.
  158.  *
  159.  * The values ALL_ERRORS and NO_ERRORS are used as extremes for the
  160.  * cpicerr_set_exit_level() and cpicerr_set_show_level() calls, and are
  161.  * not actual classification values.
  162.  *****************************************************************************/
  163. typedef enum {
  164.     RC_OK = 0,
  165.     ALL_ERRORS,
  166.     CONTINUE          ,
  167.     RETRY_VERB        ,
  168.     SECURITY_NOT_VALID,
  169.     ERROR_RECEIVED    ,
  170.     RETRY_CONV        ,
  171.     RETRY_CONV_BO     ,
  172.     BACKOUT_RECEIVED  ,
  173.     UNRECOVERABLE     ,
  174.     UNRECOVERABLE_BO  ,
  175.     NO_ERRORS
  176. } CPIC_RC_HANDLING;
  177.  
  178. /*
  179.  * Since CPI-C does not provide actual values that correspond to each CPI-C
  180.  * call, we have to invent our own so that we can put the call names into
  181.  * our message lists.
  182.  */
  183. typedef enum {
  184.     MSG_CMACCP,
  185.     MSG_CMALLC,
  186.     MSG_CMCFM ,
  187.     MSG_CMCFMD,
  188.     MSG_CMDEAL,
  189.     MSG_CMECS ,
  190.     MSG_CMECT ,
  191.     MSG_CMEMN ,
  192.     MSG_CMEPLN,
  193.     MSG_CMESL ,
  194.     MSG_CMFLUS,
  195.     MSG_CMINIT,
  196.     MSG_CMPTR ,
  197.     MSG_CMRCV ,
  198.     MSG_CMRTS ,
  199.     MSG_CMSCT ,
  200.     MSG_CMSDT ,
  201.     MSG_CMSED ,
  202.     MSG_CMSEND,
  203.     MSG_CMSERR,
  204.     MSG_CMSF  ,
  205.     MSG_CMSLD ,
  206.     MSG_CMSMN ,
  207.     MSG_CMSPLN,
  208.     MSG_CMSPTR,
  209.     MSG_CMSRC ,
  210.     MSG_CMSRT ,
  211.     MSG_CMSSL ,
  212.     MSG_CMSST ,
  213.     MSG_CMSTPN,
  214.     MSG_CMTRTS,
  215.     MSG_XCSCSU,
  216.     MSG_XCSCST,
  217.     MSG_XCSCSP
  218. } CPIC_VERB_INDEX;
  219.  
  220. /*****************************************************************************
  221.  * This structure contains all of the information necessary to for all
  222.  * cpicerr calls.  All of the fields which need to be changed by the
  223.  * application program should be modified through the cpicerr_set...()
  224.  * calls.  The application program should never have to access the
  225.  * cpicerr structure directly.
  226.  *
  227.  * When an unexpected return code occurs, this structure is used to
  228.  * determine what error processing should occur, including:
  229.  *   display of minimal error information
  230.  *   logging of complete error information
  231.  *     where to log the data
  232.  *
  233.  * If a field is added to this structure, be sure to add the correct
  234.  * initialization values for the field in the cpicerr_new() function.
  235.  *****************************************************************************/
  236.  
  237. typedef struct error_handler_cpicerr {
  238.     char * program_name;                    /* program's name                */
  239.     char * program_info;                    /* program information           */
  240.     CPIC_VERB_INDEX verb_index;             /* index of the failing verb     */
  241.     CM_RETURN_CODE conv_rc;                 /* return code from CPI-C        */
  242.     CM_INT32 mode_name_length;              /* mode_name length              */
  243.     CM_INT32 partner_LU_name_length;        /* partner_LU_name length        */
  244.     CM_CONVERSATION_STATE conversation_state;
  245.     CM_CONVERSATION_TYPE  conversation_type;
  246.     CM_SYNC_LEVEL         sync_level;
  247.     char * log_file_path;                   /* path for the log file         */
  248.     char * log_file_name;                   /* where to log errors           */
  249.     unsigned char conversation_id[8];       /* CPI-C Conversation ID         */
  250.     int  conv_id_set;                       /* Was conv_id set?              */
  251.     unsigned char mode_name[MAX_MODE_NAME]; /* mode_name                     */
  252.     unsigned char partner_LU_name[MAX_FQPLU_NAME]; /* partner_LU_name        */
  253.     CPIC_RC_HANDLING exit_level;            /* should we exit on an error?   */
  254.     CPIC_RC_HANDLING show_level;            /* should we show errors?        */
  255.     CPIC_RC_HANDLING log_level;             /* should we log errors?         */
  256.     char          major_version;            /* Major version number          */
  257.     char          minor_version;            /* Minor version number          */
  258. #ifndef TIME_NOT_SUPPORTED
  259.     time_t program_start_time;              /* time of cpicerr init          */
  260.     time_t program_error_time;              /* time of error report          */
  261. #endif
  262. } CPICERR;
  263.  
  264.  
  265. /*****************************************************************************
  266.  * The following are the structures and constants used for handling all of
  267.  * message strings in CPICERR.
  268.  *****************************************************************************/
  269.  
  270. /*
  271.  * The cpicerr_message structure contains an index and the text message
  272.  * associated with that index.  In most cases, the index will be an actual
  273.  * CPI-C return value.  For example,
  274.  * index = CM_SEND_STATE, message = "Send state"
  275.  */
  276. typedef struct cpicerr_message {
  277.     CM_INT32   index;
  278.     char *     message;
  279. } CPICERR_MESSAGE;
  280.  
  281. /*
  282.  * Each of the following is a list of messages, which are actually defined
  283.  * in the CPICERR.C file.  The messages are grouped together.  For example,
  284.  * all of the return code messages are in the cpicerr_return_codes list.
  285.  */
  286. extern CPICERR_MESSAGE cpicerr_verbs_short[];
  287. extern CPICERR_MESSAGE cpicerr_verbs_long[];
  288. extern CPICERR_MESSAGE cpicerr_return_codes[];
  289. extern CPICERR_MESSAGE cpicerr_rc_classes[];
  290. extern CPICERR_MESSAGE cpicerr_states_conv[];
  291. extern CPICERR_MESSAGE cpicerr_conv_types[];
  292. extern CPICERR_MESSAGE cpicerr_sync_levels[];
  293.  
  294. /*
  295.  * This enum gives each list a label and a value to make it easier to
  296.  * process all of the lists.
  297.  */
  298. typedef enum cpicerr_message_type {
  299.     CPIC_SYNC_LEVELS  = 1,
  300.     CPIC_CONV_TYPES   = 2,
  301.     CPIC_STATES_CONV  = 3,
  302.     CPIC_RC_CLASSES   = 4,
  303.     CPIC_RETURN_CODES = 5,
  304.     CPIC_VERBS_SHORT  = 6,
  305.     CPIC_VERBS_LONG   = 7
  306. } CPICERR_MESSAGE_TYPE;
  307.  
  308. /*
  309.  * The CPICERR_MESSAGE_LIST structure is what actually ties a
  310.  * CPICERR_MESSAGE_TYPE value to the CPICERR_MESSAGE list that it relates
  311.  * to.  A table is defined in CPICERR.C that allows the cpicerr_get_message
  312.  * routine to correlate a message label to its corresponding message list.
  313.  */
  314. typedef struct cpicerr_message_list {
  315.     CPICERR_MESSAGE_TYPE type;
  316.     CPICERR_MESSAGE *    list;
  317. } CPICERR_MESSAGE_LIST;
  318.  
  319. /*
  320.  * The following value is used to mark the end of CPICERR_MESSAGE lists.
  321.  */
  322. #define  MAX_MESSAGE       32767
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330. /*
  331.  * If these CPI-C calls are not supported, these values will be returned
  332.  * instead of a valid CPI-C values.  In the message tables, the values
  333.  * below will result in a message of "XXX not supported".  This allows
  334.  * us to differentiate between a call not being available on a platform,
  335.  * and an unrecognized value returned on a call.
  336.  */
  337. #define CMECS_NOT_SUPPORTED              (CM_CONVERSATION_STATE) 99
  338. #define CMECT_NOT_SUPPORTED              (CM_CONVERSATION_TYPE)  99
  339.  
  340.  
  341.  
  342. /*
  343.  * Used by the cpicerr_exchange_version() routine.  Future flows may
  344.  * be prefaced with new "command values" taken from this list.
  345.  */
  346. typedef enum cpicerr_command {
  347.     CPICERR_EXCHANGE_VERSION = 1
  348. } CPICERR_COMMAND;
  349.  
  350. /*****************************************************************************
  351.  * Function prototypes for routines that can be called via an application
  352.  * program.  See CPICERR.C for a full description of each function and
  353.  * how to use it.
  354.  *****************************************************************************/
  355. CPICERR *
  356. cpicerr_new(void);
  357.  
  358. int    cpicerr_set_program_name( CPICERR *            cpicerr,
  359.                                  char *               program_name);
  360. int    cpicerr_set_program_info( CPICERR *            cpicerr,
  361.                                  char *               program_info);
  362. int    cpicerr_set_major_version(CPICERR *            cpicerr,
  363.                                  char                 major_version);
  364. int    cpicerr_set_minor_version(CPICERR *            cpicerr,
  365.                                  char                 minor_version);
  366. int    cpicerr_set_conv_id(      CPICERR *            cpicerr,
  367.                                  unsigned char *      cm_conv_id);
  368. int    cpicerr_set_log_file_name(CPICERR *            cpicerr,
  369.                                  char *               log_file_name);
  370. int    cpicerr_set_log_file_path(CPICERR *            cpicerr,
  371.                                  char *               log_file_path);
  372. int    cpicerr_set_exit_level(   CPICERR *            cpicerr,
  373.                                  CPIC_RC_HANDLING     exit_level);
  374. int    cpicerr_set_show_level(   CPICERR *            cpicerr,
  375.                                  CPIC_RC_HANDLING     show_level);
  376. int    cpicerr_set_log_level(    CPICERR *            cpicerr,
  377.                                  CPIC_RC_HANDLING     log_level);
  378. CPIC_RC_HANDLING
  379. cpicerr_handle_rc(               CPICERR *            cpicerr,
  380.                                  CPIC_VERB_INDEX      verb_index,
  381.                                  CM_RETURN_CODE       conv_rc);
  382. int    cpicerr_exchange_version( CPICERR *            cpicerr,
  383.                                  unsigned char *      cm_conv_id,
  384.                                  CM_INT32             conv_state,
  385.                                  char *               partner_major_version,
  386.                                  char *               partner_minor_version);
  387. void   cpicerr_destroy(          CPICERR *            cpicerr);
  388.  
  389.  
  390. /*****************************************************************************
  391.  * Function prototypes for internal routines.  In general, these should
  392.  * not be called directly by an application program.
  393.  *****************************************************************************/
  394. void   cpicerr_classify_rc(      CM_RETURN_CODE       conv_rc,
  395.                                  CPIC_RC_HANDLING *   classification);
  396. void   cpicerr_show_rc(          CPICERR *            cpicerr,
  397.                                  FILE *               target_file);
  398. int    cpicerr_log_cpicerr(      CPICERR *            cpicerr);
  399. char * cpicerr_get_message(      CPICERR_MESSAGE_TYPE message_type,
  400.                                  CM_INT32             index);
  401. void   cpicerr_free_cpicerr(     CPICERR *            cpicerr);
  402. void   cpicerr_set_rc_info(      CPICERR *            cpicerr,
  403.                                  CPIC_VERB_INDEX      verb_index,
  404.                                  CM_RETURN_CODE       conv_rc);
  405. void   cpicerr_show_product_info(CPICERR *            cpicerr,
  406.                                  FILE *               target_file);
  407.  
  408. /*****************************************************************************
  409.  * The following function prototypes and macros are used only by the
  410.  * OS/2 specific code used to obtain the sense data after an
  411.  * allocation failure.  They are not necessary, if GET_OS2_SENSE_DATA
  412.  * has not been externally defined (with the -D compile flag).
  413.  *****************************************************************************/
  414. #ifdef GET_OS2_SENSE_DATA
  415. cpicerr_os2_appc_allocate(       CPICERR *            cpicerr,
  416.                                  FILE *               target_file);
  417.  
  418. USHORT
  419. parse_destination(char * in_string,
  420.                   char * plu_alias,
  421.                   char * fqplu_name);
  422.  
  423.  
  424.  
  425.  
  426. /* Macro BLANK_STRING sets string to all blanks */
  427. #define BLANK_STRING(str)  memset(str,(int)' ',sizeof(str))
  428.  
  429. #undef CLEAR_VCB
  430. /* Macro CLEAR_VCB sets the APPC verb control block to zeros */
  431. #define CLEAR_VCB(vcb)     memset((char *)&vcb,(int)'\0',sizeof(vcb))
  432.  
  433. /* convert a string to uppercase, up to length specified */
  434. #define TOUPPER_STRING(str,length) \
  435.                            {int i; for (i=0;i < length;i ++) \
  436.                            {str[i] = (char)toupper(str[i]);}}
  437.  
  438. /* convert an ASCII blank padded string to an ASCIIZ string without pads */
  439. #define SNA2STRING(outstr, instr, max_length) \
  440.                    {int i; for (i=0;i < max_length && instr[i] != ' ';i ++) \
  441.                    {outstr[i] = instr[i];} outstr[i] = '\0';}
  442.  
  443. #endif
  444.  
  445. #endif
  446.